# JBuilder 4

## Release Notes

This document contains a subset of known problems, workarounds and tips for JBuilder 4.

> ### Late-Breaking News

> Windows Users: If you encounter problems debugging your applications using JBuilder 4, please do the following:
> 1. Check the JavaSoft web site for updates and patches to the Windows version of JDK 1.3: http://www.javasoft.com/j2se/1.3/.
> 2. Add the `-classic` option as the first VM parameter in your project (Project|Project Properties, Run tab, VM Parameters) when debugging.

## Table of Contents

> General
> Installation
> Enterprise JavaBeans (EJB)
> Web Development
> Team Development
> Editor
> Components
> Debugger
> Designer
> Database and JDataStore
> Wizards
> Runtime
> Help Viewer
> OpenTools
> Linux
> Inprise Application Server
> Samples
> Performance
> International
> Documentation

## General

### Tips:

- If you experience significant repainting or flickering problems under Windows, try uncommenting the following line in the `jdk.config` file:

  >     vmparam -Dsun.java2d.noddraw

- When Check Stable Packages is turned off, the JBuilder Dependency Checker assumes that any compiled packages not in the current project are stable and will not check their source files for changes. All classes contained in archives (zip, jar, war, etc.) will also not be checked for changed source. When Check Stable Packages is turned on, the Dependency Checker will always check the state of source files not in archives.

#### Using JBuilder 3.5 and JBuilder 4

Some of the changes in JBuilder 4 make it extremely inconvenient to share the ".jbuilder" directory with an installation of JBuilder 3.5. As a service to our customers, we put the settings for JBuilder 4 in new directory, `.jbuilder4`, and settings for JDataStore 4 in `.jdatastore4`.

- Any components that you added to the palette in JBuilder 3.5 will need to be added again to JBuilder 4.
- Any connections you defined for JBuilder 3.5 will need to be re-defined for JBuilder 4.
- Opening JBuilder 4 Projects using JBuilder 3.5
  JBuilder 3.5 does not recognize archive nodes, new to JBuilder 4. Opening a JBuilder 4 project in JBuilder 3.5 will cause these nodes and the information they contain to be lost.
- You can change the location where JBuilder looks for your .jbuilder4 by adding the following entry in the `jbuilder.config` file:

  >     vmparam -Djbuilder.home=path to the parent directory for .jbuilder4-dir

  where .jbuilder4-dir is the name of your alternate home directory.

### Known problems:

- [81326] JBuilder does not recognize symbolic links when trying to browse into a directory structure.
- [89608] Exiting JBuilder without stopping a running RMI Registry process will leave the process running.
- [91775] Using the `jbuilder -build` command-line does not work with paths that contain spaces, even if you add quotes around the path.
  Workaround: Avoid creating and using directories that contain spaces.

## What's new in JBuilder 4

See What's New in JBuilder 4 in the Quick Start for information about new features and functionality.

[ top ]

## Installation

### Tips:

For explicit install instructions, look at setup_<platform>.html. It is very important to follow those directions.

### Linux

Possible Problem: System minimum configuration meets or exceeds specified requirements, but JBuilder runs slow.

Solution: The Linux kernel has problems with a few motherboard/BIOS not reporting total memory available. To check that all installed memory is being recognized, type the following at a shell prompt:

>     cat /proc/meminfo

the output will include a line looking like:

>     MemTotal: ######## kB

where "########" should equal the amount of memory your computer has. If it doesn't, you'll need to explicitly tell the kernel by editing the file /etc/lilo.conf.

Details for doing this can be found at: http://www.redhat.com/support/docs/faqs/rhl_general_faq/FAQ-7.html

### Uninstalling JBuilder

To uninstall JBuilder:

1. Locate the directory where JBuilder was installed.
2. Delete the JBuilder directory.
3. Delete the `.jbuilder4` directory:
   - Linux: in your home directory.
   - Solaris: in your home directory.
   - Windows: in Windows directory (for Windows 98) or your home directory (for Windows NT). Also, delete the items in the Start menu: Start|Programs|JBuilder 4|right-click|Delete.

### Known problems:

- [75016] Linux only: Install hangs with no message if not running under X-windows.
  Workaround: Run the installation program only under X-Windows.
- [84133] Windows only: The installation programs leaves temporary files in your TEMP directory.
  Workaround: After you completed installing JBuilder, you can delete these directories.
- Solaris only:
  - The 'Browse CD' button does not work on the main installation launcher.
    Workaround: Verify that `dtfile` (typically in `/usr/dt/bin`) is in your PATH.
  - The "Register" or "?" (Installation help) buttons do not work.
    Workaround: Verify that `netscape` (typically in `/opt/NSCPcom`) is in your PATH.

[ top ]

## Enterprise JavaBeans (EJB)

> You must use version 4.1.1 or higher of the Inprise Application Server, or the Enterprise JavaBeans development features in JBuilder 4 will not function properly. Inprise Application Server 4.1.1 is the version installed with JBuilder Enterprise.

> See the Enterprise JavaBeans Developer's Guide for a tutorial and additional information on developing and deploying EJBs using JBuilder 4.

### Known problems:

- To deploy your EJBs to a WebLogic container from within JBuilder:
  1. Use the WebLogic deployment tool to create (generate container classes) and deploy the jar to the server (local/remote).
  2. From JBuilder, choose Project|Project properties, Run page. EJB. Add the following parameter to the VM parameter list:

         -Dweblogic.ejb.deploy=complete path to jar/jarname.jar

     or add the following line to the `weblogic.properties` file in your WebLogic home directory:

         weblogic.ejb.deploy=\complete path to jar/jarname.jar

  3. On the Run page uncheck the box 'Compile before running' and run the project.
- The WebLogic `ejbc` compiler generates compilation errors in the following cases:
  - The Weblogic project is created in a directory which contains spaces.
  - The classpath contains spaces.
  Users should avoid spaces in the project directory or the classpath.
- [88651] Get a verify error from the DD Editor if you have a custom interface that either the home or remote interface extends, and you explicitly specify a container transaction assignment to a method in that custom interface.
  Workaround: Set the configuration for the Inprise Application Server to use class reflection. To do this, add `UseSourceReflection=false` as a Preference entry to the `IAS41/console/plugins/iaspt.ini` file.
- [89609] Exiting JBuilder without stopping a running OSagent process will leave the process running.
- [90078] Switching from the Inprise Application Server to WebLogic should also update the Build page.
  Workaround: Close the "Default Project Properties" dialog and bring up again.
- [90648] WebLogic users cannot deploy unless the Inprise Application Server is installed, set up and JBuilder restarted first.
- [91233] BeansExpress on an EJB may not correctly reflect the current state of the source when using classes with one or more levels of inheritance.
  Workaround: Re-compile the class. BeansExpress should then reflect the correct state of the source.
- [91037] If there is a parsing error in the source of one the of EJB classes, and you open the Project, you get stack traces in the console window, "Invalid EJB Deployment Descriptor" message in the Content Pane, and "com.borland.jbuilder.jot.JotParseException: expected at line 18" in the Message Pane.
  Workaround: Re-compile the class before continuing. Also, exit the DD Editor and re-start it.

[ top ]

## Web Development

The JSWDK1.0 library is now obsolete; JBuilder now uses the Tomcat servlet engine. Because of the new web server integration, there is no need to declare a web server library, and there is no Tomcat library to replace JSWDK. If you have existing projects that use the JSWDK1.0 library, you should remove it from those projects as a required library.

### Known problems:

- Before debugging JavaServer Pages (JSPs) or servlets under Windows, add the `-classic` option as the first VM parameter for the JSP/Servlet run configuration (Project|Project Properties, Run tab, JSP/Servlet tab, VM Parameters). When JDK 1.3 for Windows is updated to resolve the HotSpot debugging problem, you can remove the parameter.
- Code generated using the Servlet Wizard from previous releases will not work properly without making the following changes to your code:
  1. Change the following line:
     `PrintWriter out = new PrintWriter (response.getOutputStream());`
     to:
     `PrintWriter out = response.getWriter();`
  2. Delete the following line:
     `out.close();`
- [89997] Posting an HTML form from Web View causes the error message, `Error reading request connection reset`, to appear every time.
  Workaround: The post occurred correctly. The error message can be ignored.
- [91877] The IxTableCellRenderer interface is not public.
  Workaround: Extend IxTableCell, which implements IxTableCellRenderer, and override any behavior you don't want.

[ top ]

## Team Development

To take full advantage of CVS capabilities in JBuilder, it is recommended that you use CVS version 1.10.8 or later.

### Known problems:

- [89056] Cannot create a new module from an existing project. The Create menu choice is not available. (The export functionality is not supported in this release.)
- [91241] Checking in a .jpr project checks in the .jpr.local file.
  Workaround: Projects saved as JPR projects should be saved as JPX projects in order to take advantage of team development features.

### Using CVS with SSH

It is possible to use SSH to have a secure connection to a CVS server when using the Team Development features of JBuilder. SSH provides a way of connecting to a host machine using strong encryption, thus assuring that confidential data is kept...confidential.

JBuilder supports this option. You need to use SSH1 (SSH2 could work but has not been tested) and the connection has to be configured in such a way that SSH will not prompt for a password. This is extremely important. Failing to configure SSH to connect without a password will cause JBuilder to "freeze" until the SSH program is explictly terminated. (Please refer to the SSH documentation for more information.)

To test if your connection is configured correctly, before trying it in JBuilder, enter `ssh` followed by the name of the server you want to connect to. For example, if the server is called `codecentral`, enter:

>     ssh codecentral

If SSH connects to the server without prompting you for a password, you can use SSH in JBuilder.

After SSH is properly configured, you need to specify some parameters on the CVS configuration page. To do this:

1. Choose Team|Configure Version Control.
2. From the CVS configuration page, select "Ext" for the connection type.
3. Enter the name of the server and your username on that server.
4. For "Remote shell", enter `ssh`.

After these parameters have been specified, you can perform all the CVS operations in a secure enviroment that uses strong encryption for data transfer.

[ top ]

## Editor

### Known problems:

- Cursor position may not reflect actual position at times for multi-byte characters. Workaround is to turn off the Bold attribute for syntax highlighting in Tools|Editor Options|Color. (JavaSoft Bug)
- [73956] Under KDE, Ctrl + F4 switches to desktop #4 instead of closing the editor tab that currently has focus.

[ top ]

## Components

### Editing date values

To help prevent unexpected results when date values are edited, dbSwing and JBCL components convert the default pattern's two-digit year to a four-digit year. dbSwing's JdbTextField and JdbTable also substitute a four-digit year when a custom displayMask is used to control editing (but not when you specify an editMask, because then it controls editing). JdbTextField does this conversion when a date or timestamp is displayed; the other components wait until the date or timestamp is edited. The pattern used to parse edited values is not changed.

To understand the reason for this, you must be aware of Java's default behavior when parsing a date value using a pattern that specifies a two-digit year. If the date string contains a two-digit year, the year is assumed to fall in a window that runs from 80 years before the current date to 20 years in the future; otherwise (that is, the year is one, three, or four digits long), the year is taken just as it is. To see the implications of this rule, consider an example:

- This character string is parsed: "9/23/2085"
- The value in the resulting date object is: September 23, 2085
- With the default formatting, this is displayed as: "9/23/85"
- The string is edited: "10/23/85"
- Parsing it gives this value in a date object: October 23, 1985
- Only the month was edited, but the century also changed.

Forcing the full four-digit year to be displayed prevents this behavior. When entering a new value, you can still enter a two-digit year and let Java determine whether it's in the 20th or 21st century, or you can specify the century yourself by entering all four digits. One warning: always represent a year between 2000 and 2009 as a two-digit string with a leading zero. As the rule above states, a one-digit year is not treated as falling somewhere in the 20th or 21st century.

### Known problems:

- [76021] The BeanChooser looks for information in source jars instead of class jars. If you don't have the source for the classes, you will see incomplete lists of which classes are available.
  Workaround: Enter the name of the class manually.
- [88009] The setWidth() method on a TableColumn (as obtained from a jdbTable) has no effect on the UI.
  Workaround: Use setPreferredWidth() instead.
- [88010] When you change the width of a TableColumn (as obtained from a jdbTable) the column header does not change width to match.
  Workaround: Call JdbTable.createDefaultColumnsFromModel() after changing the width, then the headers will match.

[ top ]

## Debugger

### Tips:

- Due to a change in the Project file format, breakpoints in projects created prior to this release will no longer be visible.
- When a class is compiled without debug information, the debugger will not be able to see any local variable information. However, it can see the "this" object. If you are debugging and only the "this" object shows up, it could mean that the class was built with no debug information. It could also mean that there are no local variables in the class.
- In the current version of JDK 1.3, debugging using the classic VM is much faster than debugging with HotSpot. If you see a noticeable slowdown in your program when you debug it, try adding the `-classic` option as the first VM parameter in your project (Project|Project Properties, Run tab, VM Parameters) before you debug.

### Debugging applets from within a browser (IE 5 or Netscape Navigator 4.72) using JDK 1.3

1. Download and install the plugin for JDK 1.3 from the Sun site: http://java.sun.com/products/plugin/
2. Download and install the HTML converter from the Sun site http://java.sun.com/products/plugin/1.3/features.html.
3. Follow instructions to set the debug parameters for the Java Plugin for applets: http://java.sun.com/products/plugin/1.3/docs/debugging.html.
   Add -classic as the first parameter to use the Classic VM for debugging (if appropriate).
4. Using JBuilder:
   1. Create a simple applet with an HTML file.
   2. Compile the project.
   3. Convert the HTML file using the HTML converter. Instructions to use the HTML converter can be found at: http://java.sun.com/products/plugin/1.3/docs/htmlconv.html.
   4. Set breakpoint in the applet file. In the project properties debug page, enable remote debugging and enter the following parameters:
      - If using dt_shmem and address javadebug, select transport dt_shmem and enter address 'javadebug'.
      - If using dt_socket, select transport dt_socket and enter the address you have provided in the control panel (default provided in JBuilder is 5000). For further information on remote debugging, see "Debugging distributed applications" in the Distributed Application Developer's Guide.
5. Start up the browser (either Netscape or IE). Open the html file. Switch to JBuilder and start debugging your project. The debugger should start up successfully. Switch back to the browser and refresh the page. In JBuilder, the debugger should have stopped at the breakpoint in the applet.

### Known problems:

- Evaluator cannot evaluate expressions containing array definitions - e.g. i1 = new int[10] where i1 is an array of int.
- Instability may occur when debugging with IBM's JDK 1.3 on Red Hat Linux (6.2). Report problems, with steps as usual.
- [84700] Cannot remove a breakpoint which while debugging a program. The program has to be stopped and the breakpoint removed from the View | Breakpoints dialog. (Windows 98)

  This happens only when debugging with files on Windows 98 which were created using Windows NT. This is Windows 98 FAT32 bug. All files created using Windows NT will be converted to either all uppercase or the first letter to uppercase. Since the breakpoint is saved in case-sensitive form, the breakpoint is not recognized and cannot be removed.

- [86509] Cannot debug a project in a directory which is a symbolic link.
  Workaround: Debug using the actual directory and not the symbolic link to it.

[ top ]

## Designer

### Tips:

"Red Beans"

If you see one of your components as a red box with its class name at the top, JBuilder has not been able to create an instance of that component for the designer. This is called a "Red Bean". Some reasons you might see a Red Bean are:

- The class or its constructor is not public.
- The class threw exceptions on every constructor JBuilder tried.
- The class is the "this" object and it extends an abstract class.

Items (1) and (2) can be fixed by supplying a proper default constructor or subclassing that class in order to provide a default constructor. Item (3) is more complex. Whenever JBuilder needs to instantiate an object to be the 'this' object, it encounters a paradox. It cannot instantiate the object you are designing. To circumvent this problem, JBuilder always attempts to instantiate the superclass of the "this" object. If the superclass is abstract, it cannot be instantiated. Here is the solution:

In the file ".jbuilder4/user.properties," you will find a line that looks like:

>     designer;proxy.java.awt.Component=com.borland.jbuilder.designer.dt.ComponentProxy

This line says that whenever you are forced to instantiate com.sun.java.swing.JComponent (which is abstract), you will find an acceptable concrete proxy class for it in:

>     com.borland.jbuilder.dt.JComponentProxy

You may add your own proxy objects using this pattern. The proxy class does not need to do anything other than the following:

1. Extend the abstract class in question.
2. Be concrete (not be declared abstract itself).
3. Be public (both the class and its constructor).

### Known problems:

- [87957] Cannot open a form generated by Data Module Application wizard in the Designer. The error message "class java.lang.NullPointerException null" comes up in message pane.
  Workaround: Rebuild All after generating the form before starting the Designer.
- [91297] Using the Sun JDK, under the CDE/Motif Look & Feel, you cannot set the background property of a JComboBox without getting a NullPointerException when the code is run. The Designer prevents the user from setting this property when under CDE/Motif. If users hand-code the setBackground property, then tries to run under Motif, they will get the exception.

[ top ]

## Database and JDataStore

### Tips:

- When creating new JDataStores using the JDataStore Explorer, you can specify the version of the new JDataStore. Using the JDataStore Explorer,
  1. Choose File|New.
  2. For File version, select one of the two options:
     - JDS 3.51 and IAS 4.1x compatible
       Selecting this option sets the new JDataStore to be created so that it is compatible with the Inprise Application Server 4.1x or other applications that use JDataStore 3.51. If you select this option, you cannot use new JDataStore 4 features such as user authentication or encryption.
     - JDS 4
       Selecting this option sets the new JDataStore to be created so you can take advantage of new JDataStore 4 features, such as user authentication or encryption. If you select this option, the JDataStore you create cannot be used by the Inprise Application Server or other applications that use JDataStore 3.51.
  If you create a 3.51 JDataStore, or have an existing 3.51 JDataStore, and you wish to add JDS 4 features to that JDataStore, you can upgrade it at any time. To do so:
  1. Start the JDataStore Explorer
  2. Open the 3.51 JDataStore you want to upgrade.
  3. Choose Tools|Upgrade.
- The DataStore component has a new method: `public synchronized final void setVersion(int version)`. If you want to call this method, you must call it before calling `DataStore.create()`. If you do not call this method, the version defaults to DataStore.STORE_VERSION. You can specify one of two values as a parameter:
  - `DataStore.VERSION_5_0`
  - `DataStore.STORE_VERSION`
  If you specify DataStore.VERSION_5_0, then the JDataStore that is created will be compatible with the Inprise Application Server 4.1x or other applications using JDataStore 3.51.
- In order to use DataExpress's new components for connection pooling (in the com.borland.javax.sql package), you will need to have an Java 2 Enterprise Edition (J2EE) implementation on your classpath. The preferred way to do this is to install the Inprise Application Server (included with JBuilder Enterprise). You can also download J2EE release 1.2.1 from java.sun.com/j2ee/download.html.

  After you have installed a J2EE implementation, add the following lines to your `jbuilder.config` file:

  >     addpath C:/j2sdkee1.2.1/lib/j2ee.jar
  >     addpath C:/j2sdkee1.2.1/lib/jhall.jar
  >     addpath C:/j2sdkee1.2.1/lib/ejb10deployment.jar

  You will also need to create a Library for J2EE in JBuilder:

  1. Start JBuilder.
  2. Choose Tools|Configure Libraries.
  3. Click New.
  4. Enter the name for the new library (e.g. J2EE1.2.1).
  5. Click Add.
  6. Drill down to the place the .jar files are located.
  7. Select the three J2EE .jar files and press OK.
  8. Click OK.
- A LOCK command has been added to the SQL dialect supported by JDataStore's JDBC driver. By locking all the tables a transaction needs at the start of a transaction, you can ensure that it will not deadlock with another transaction that tries to access the same tables in a different sequence. The syntax is:

  >     LOCK <table reference list>

  where "<table reference list>" is a comma-separated list of table references.

- For performance and memory reasons, the behavior of `distinct` has been modified. You can no longer rely on `dist`ing sorting strings in an alphabetic order. The sorting now prepends the string length in the sort key. This makes shorter strings sort to the top.

  This will break applications that incorrectly relied on the ordering from a select distinct. Distinct does not guarantee order.

### Application Deployment

Information on deploying the JDataStore JDBC server for remote access is described in "Deploying the JDataStore JDBC server" in the JDataStore Developer's Guide. Tips for reducing the deployed size of JDataStore client applications can be found in "Pruning deployed resources" in the JDataStore Developer's Guide.

### Adding a JDBC driver to JBuilder

After installing your JDBC driver following the manufacturer's instructions, use the steps below to set it up for use with JBuilder.

Note: Drivers listed in red on the Drivers list (in the Connection Property dialog box, JDBC Explorer, or JDataStore Explorer) are not on the classpath. While you can select them, any connections or URLs you define using them will not work until they have been added to your classpath.

#### Creating the .library and .config files

There are three steps to adding a database driver to JBuilder:

- Creating a library file which contains the driver's classes, typically a JAR file, and any other auxiliary files such as documentation and source.
- Deriving a .config file from the library file which JBuilder adds to its classpath at start-up.
- Adding the new library to your project, or to the Default project if you want it available for all new projects.

The first two steps can be accomplished in one dialog box:

1. Open JBuilder and choose Tools|Enterprise Setup. Click the Database Drivers tab which displays .config files for all the currently known database drivers.
2. Click Add to add a new driver, then New to first create a new library file for the driver. The library file is used to add the driver to the required libraries list for projects. Note: You can also create a new library under Tools|Configure Libraries, but since you would then have to use Enterprise Setup to derive the .config file, it is simpler to do it all here.
3. Type a name and select a location for the new file in the Create New Library dialog box.
4. Click Add, and browse to the location of the driver. You can select the directory containing the driver and all it's support files, or you can select just the archive file for the driver. Either will work. JBuilder will extract the information it needs.
5. Click OK to close the file browser. This displays the new library at the bottom of the library list and selects it.
6. Click OK. JBuilder creates a new .library file in the JBuilder `/lib` directory with the name you specified (for example, `InterClient.library`). It also returns you to the Database Drivers page which displays the name of the corresponding .config file in the list which will be derived from the library file (for example, `InterClient.config`).
7. Click OK. This places the .config file in the JBuilder `/lib/ext` directory.
8. Close and restart JBuilder so the changes to the database drivers will take effect, and the new driver will be put on the JBuilder classpath.

Important: If you make changes to the `.library` file after the `.config` file has been derived, you must re-generate the `.config` file using Enterprise Setup, then restart JBuilder.

#### Adding the JDBC driver to projects

Projects run from within JBuilder use only the classpath defined for that project. Therefore, to make sure the JDBC driver is available for all new projects that will need it, define the library and add it to your default list of required libraries. This is done from within JBuilder using the following steps:

1. Start JBuilder and close any open projects.
2. Choose Project|Default Project Properties.
3. Select the Required Libraries tab on the Paths page, then click the Add button.
4. Select the new JDBC driver from the library list and click OK.
5. Click OK to close the Default Project Properties dialog box.

Note: You can also add the JDBC driver to an existing project. Just open the project, then choose Project|Properties and use the same process as above.

Now JBuilder and the new JDBC driver are set up to work together. The next step is to create or open a project that uses this driver, add a Database component to it, and set its `connection` property so it can use that driver to access the data. For an example of how to do this, see "Tutorial: Connecting to a database using InterClient" in the Database Application Developer's Guide.

### Known problems:

- [86280] The JDataStore Explorer always prompts for a username and password, even if the JDataStore does not require one.
  Workaround: If no username or password is required for the DataStore, just click OK when prompted. The DataStore will be opened.
- To use the new ConnectionPool support with WebBench you will need to have a Java 2 Enterprise Edition (J2EE) implementation on your classpath. Click here for instructions on installing and configuring a Java 2 Enterprise Edition (J2EE) implementation.
- To enable the following components, located on the "DataExpress" tab:
  - com.borland.javax.sql.JdbcDataSource
  - com.borland.javax.sql.JdbcConnectionPool
  - com.borland.javax.sql.JdbcConnectionFactory
  you must install the Java 2 Enterprise Edition, version 1.2.1 libraries. Click here for instructions on installing and configuring a Java 2 Enterprise Edition (J2EE) implementation.
- [85458] Using Extended properties causes an unexpected error (e.g.. In the JDBC Explorer using the InterClient driver). If you check the Use Extended Properties option for a table, an error message box is displayed when connecting to the table: "Invalid argument User and password connection properties are not set."
  Note: This is not an error, but a feature of JDBC. If you use extended properties, the username you see in the JDBC Explorer is ignored and you are not prompted for a user/name password. When you use extended properties, you need to specify the username/password as entries in the extended properties. The username is displayed in italics if "Use Extended Properties" is checked, indicating that the username will be ignored.
- [89188] When a DataStore is Encrypted, all the startup rights of the non-administrator users added prior to encryption are lost and have to be reissued.
- [91165] ReadOnly Connections should not be set with AutoCommit on. With many connections open, you might run out of memory.
- [91723] jsql.config doesn't find database drivers that have been added to JBuilder.
  Workaround: Add these two lines after its addpath directives:
  `# Add all the configuration files located in the lib/ext directory
  includedir ../lib/ext`

[ top ]

## Wizards

### Known problems:

- Code generated using the Servlet Wizard from previous releases without not work properly without making the following changes to your code:
  1. Change the following line:
     `PrintWriter out = new PrintWriter (response.getOutputStream());`
     to:
     `PrintWriter out = response.getWriter();`
  2. Delete the following line:
     `out.close();`

[ top ]

## Runtime

### Running JDK 1.2 Applets

In order to run an Applet on Solaris or Linux from within JBuilder, you must add the Open Tools SDK library to your project. Failing to add this library can lead to an exception about a "NoClassDefFoundError:AppletTestbed." This problem currently affects some of the applet samples, including the Primes Swing sample.

### Running JDK 1.1.x Applets

The Project Properties|Run page for applets lets you specify whether to run your applet from the applet's main class or from the HTML file:

- If you run the applet from the HTML file, then the applet is run using the AppletViewer from the JDK.
- If you run the applet from its main class, the applet is run using JBuilder's AppletTestBed. Before you can run your applet, you need to:
  1. download the JDK 1.1.x specific version of JFC (Swing) from the JavaSoft site.
  2. Create a library for the JFC classes and add the library to the project.

### Known Problems:

- [71959] Specifying more than one classpath for a -D parameter forces the VM to interpret the second classpath as the class to run.
- [80444] Get error "Can't find class com/borland/jbuilder/runtime/AppletTestbed" when running JDK 1.1.x. Error is not correct as the classes are delivered and you can run 1.2 Applets which also use this class. See workaround "Running JDK 1.1.x Applets" above in this section.
- [87430] The HTML viewer fails to show the applet, displaying a message that the applet would work in a Java-enabled browser.
  Workaround: Using the AppletViewer supplied with the JDK to view your applet.

[ top ]

## Help Viewer

### Known Problems:

- [86563], [89639] Cannot set focus to the Help Viewer while a modal dialog is being displayed. The workaround is to close the dialog box before trying to access the Help Viewer window again.
  Workaround: Use your web browser to view the JBuilder online documentation. See Using JBuilder's online help for instructions on how to do this. The documentation is also available in PDF format on your product CD and from the JBuilder Technical Publications web page.
- [90465] After choosing an encoding from Options|Encoding, the HTML file is displayed incorrectly.
  Workaround: Choosing File|Reload should reload the file and cause it to display with the correct encoding.
- [91040] Quick Tips do not specify which edition of JBuilder they are applicable to: Foundation, Professional, or Enterprise.
  Workaround: When displayed as separate tips in the "Tip of the Day", only tips applicable to the edition should be displayed.

[ top ]

## Linux

### Tips:

#### Printing on Linux and Solaris platforms

A workaround for people on Unix platforms who do not need to use AWT components in the designer and want to be able to select a printer that is different than `lpr` is to comment out the line in the `JBuilder.config` file that adds the LightWeight Toolkit to the boot path as shown:

>     # Put the Lightweight Toolkit on the boot path
>     #addbootpath ../lib/lawt.jar

### Known Problems:

- [75424] Cannot directly do Cut and Paste between Java applications and the KDE utilities.
  Workaround: Use the X-windows clipboard to copy items between applications.
- [90559] When a new window pops open (CodeInsight, code templates, etc.), focus to the editor is lost. (This works properly using KDE.) Workaround: (For GNOME users) Go to the Control Center and change the "Focus Behavior" so that "Dialog windows inherit the focus from their parent" is turned off.
- [89770] CodeInsight reports unnamed parameters for methods and constructors and forces the "Browse symbol" feature to decompile a class and present the stub instead of showing the expected source. This is caused because the src.jar file is not delivered with the JDK on this platform. Check for updates at http://www.ibm.com/java/jdk/linux130/.

[ top ]

## Inprise Application Server

### Known Problems:

- [81080] Running a CORBA client a second time on some host platforms may fail unless a unique `procId` is entered.
  Workaround: Modify the client to set this property before the connection attempt. For example:

  >     System.setProperty("vbroker.orb.procId", String.valueOf(this.hashCode()));

[ top ]

## OpenTools

### Known problems:

- [82144] The OpenTools samples expect the output class path to end with the directory name 'classes' (e.g. /usr/local/jbproject/classes) and the classes.opentools file to be in the directory above the classes directory (i.e. jbproject). Specifying any other path name (without "classes" at the end) does not load the OpenTool component.
- [90993] The Open Tools SDK library does not point to the OpenTools JavaDoc in jb_opentools.jar.
  Workaround: Set the Doc path for OTAPI to JBuilder4/doc/jb_opentools.jar]/opentools/ref/OpenToolsAPI.
  If you installed JBuilder 4 to a directory other than the default, then substitute your directory for JBuilder4.

[ top ]

## Samples

The OnlineStore sample requires the use of platform-specific InterBase database (.gdb) files in the 'OnlineStore/database' subdirectory. Database files are provided for the Windows, Solaris, and Linux platforms. Before running the OnlineStore sample, you will need to copy both of the platform-specific acmecb and cliffhanger databases to filenames with the normal .gdb file extension. For example, to run the sample on Windows, copy 'acmecb.gdb.windows' to 'acmecb.gdb' and 'cliffhanger.gdb.windows' to 'cliffhanger.gdb'.

The Samples.html file should be viewed in the JBuilder AppBrowser or from the link in the Welcome Project.

### Known Problems:

- "Error # 914: unable to write to output directory". If you have installed JBuilder as root but are running as a regular user, you need to copy the entire samples tree to a directory in which you have full read/write permissions in order to run them. While it is possible to copy projects individually from the sample tree, there are several samples which require access to files in peer-level directories. Such samples have been modified to look automatically for such files relative to the default sample tree hierarchy and display a message at runtime indicating the path being used to locate such files.

  An easy way to copy the entire samples tree is to use the 'cp -R' command. For example, to copy the tree to a 'samples' subdirectory of your home directory, do the following:

  >     % cd
  >     % cp -R /usr/local/jbuilder/samples .

- [73147] You must compile the JDataStore, dbSwing and DataExpress samples before using them in the Designer. This will make classes and data available to the designer.

  If you open a sample in the Designer and get an error message such as `Filename property set to null` or `URL cannot be null`, open the file in the Source view, modify the source (such as a adding and removing a space), then rebuild the project. You should now be able to open the project in the Designer without errors.

- [87072] Chess server fails to run when launched by user (Unix only: JBuilder installed by root). The error message is: Could not listen on port: 100, java.net.BindException: Permission denied. If running as a user (not root), the basePort var in ChessServer.java has to be 1027. Line 29 in ChessServer.java is currently:

  >     final static in basePort = 101;

  To run the client, you have to change the value in this line from 101 to 1027.

- [73420] Chess viewer applet fails because of image Parameter specified in the Run Applet parameter. First, make the changes for [87072] above. To run the applet client:
  1. Select Run|Configurations.
  2. Select Chessviewer applet.
  3. Click Edit.
  4. Change the Values for the image Parameter to the correct file names and locations. For example:
     images/cmpieces.gif becomes com/borland/samples/chess/client/images/CMPIECES.GIF
- [80347] The project files for the RMI sample (and some other samples) point to /usr/local/jbuilder by default.
  Workaround: Change this path in your project settings after opening the project.
- [89125] SqlTools\xmlservlet
  1. dx.jar, datastore.jar, and dsremote.jar need to be added to the batch or shell file, if they are not already listed.
  2. JDK 1.3 needs to be in your path before running the sample.

[ top ]

## Performance

These are some suggestions for improving local performance of JBuilder 4.

- Adding "-Xverify:none" to your launch script will decrease the load time for JBuilder 4, Solaris/Linux Edition.
- Set VM heap usage settings to values you think are typical for your usage of the product. This avoids the degradation that occurs because the VM resists growing its heap. For medium to large projects, try the following VM settings:

  >     -ms48m -mx128m

  You will need to experiment and fine tune these heap settings to your usage pattern.

- JDK 1.3 uses HotSpot by default. The faster memory management of hotspot makes a significant performance improvement. If the apps you debug need to use the classic VM, add -classic to Project|Project Properties|Run tab|VM Parameters.
- You can get smoother garbage collection performance by enabling incremental gc. Use the following VM setting to do this:

  >     -Xincgc

  It is worth noting that the incremental garbage collector, while smoothing GC hiccups, also slows the VM down noticeably. We suggest using this only if you experience long GC induced pauses while using JBuilder 4.

- You can reduce the amount of background source parsing for the structure pane by increasing the parsing time delay. To do this, right click on the structure pane and select properties. Now increase the Parse Delay setting.

[ top ]

## International

### Installing to a Japanese NEC machine

[75607] If you are installing JBuilder to a Japanese NEC computer and the install program causes an operating system error message saying that "Drive C: is not ready... the drive door may be open...", then you should press the <Ignore> button in this dialog. Install will then complete normally. (The <Abort> button should also work.)

### Japanese Fonts on Linux

[75704][75705] If you experience problems displaying Japanese fonts on Linux, you may need to update the file, `<jdk1.3>/jre/lib/font.properties.ja`. JavaSoft's web site has instructions on how to do this in Japanese: Directions to modify the font.properties file (in Japanese).

### Solaris Platforms

- [70509] Turning on/off "Enable international input methods" repeatedly causes JVM crash.
- [49327] If the Sparc Compose key does not function properly, be sure that the setting, "Enable international input methods" is turned on (found under Tools|Editor Options|Editor tab|Smart key options). If the problem persists, a mouse click in the field or edit region will often cause the Compose key to work.

### Command Line Compiler

- [79877] (Windows platforms only) European versions of the command line compilers (bcj and bmj) may display accented characters incorrectly in a console window. The workaround is to invoke the compiler as follows (Note, `<path_to_JBuilder>/lib/jbuilder.jar` must be on your classpath):

  >     java -Dfile.encoding=Cp850 com.borland.compiler.frontend.Main -encoding Cp1252 myFile.java

  The first encoding option above is passed to the Virtual Machine and the second encoding option is passed to the compiler. Please note that this example assumes Code Page 850 is used in the console window (as shown by the chcp command), and that your java files are encoded in Code Page 1252 (which is the case when a Windows based editor was used, rather than an "old style" DOS-based editor).

  If your program sends accented characters to the console window, they will be displayed correctly if you use the following (assuming your console window uses Code Page 850, as shown by the DOS chcp command):

  >     java -Dfile.encoding=Cp850 myClassFile

### Other Known Problems:

- [70027] When IntlSwingSupport is dropped on a Frame in the designer, it may be instantiated after other class members such as a JFileChooser, JOptionPane, or JColorChooser, which means the translated resources are loaded too late for initial display purposes. Instantiating IntlSwingSupport as early as possible during your application startup will fix this problem.
- [73279] If the environment variable, LC_CTYPE, is set to the POSIX 'C' locale, the Sparc Compose key may not function for certain versions of Xlib client libraries.
- [65318] DBCS (for example, Japanese character set) string in .JSP returned from bean corrupts in HTML browser.
- [69954] JDK1.3 JVM couldn't handle default locale override settings on Japanese OS.
- [70954] Emacs keymap "Set Mark" is actually Ctrl-2 instead of Ctrl-Space, or Ctrl-@ under Japanese Keyboard.
- [71929] Can't display localized exception messages of the native method calls correctly under a non-English locale. If these messages must be read, UNIX users can display them in English by setting the "LANG" environment variable to the POSIX "C" locale. For example UNIX users would execute at the command prompt: export LANG=C.
- [72107] Undo <Ctrl_> under Emacs keymap is mapped to <Ctrl Shift -(hyphen)> using Japanese Keyboard.
- [72519] Undo <Ctrl_> under Emacs keymap does not work using French Keyboard. The workaround is to use <Ctrl x><u> or use the keymap editor to customize the keymapping.
- [74063] (Japanese OS only) Under bold and italic attribute, the cursor will stop in the middle of a character, to workaround the problem, please add the following line to JBuilder4/bin/JBuilder.config
  `vmparam -Dprimetime.editor.useVariableWidthFont= true`
  after the update, please remove the ~/.jbuilder4/user.properties before launching JBuilder.
- [86538] Windows only: Brace matching does not work with a German keyboard driver (with German layout). Please use the Alt+' (which is located on the left of <backspace> on a German keyboard), or use the keymap editor to customize the keymapping. [86689] Open a new window will switch to default locale's keyboard, ignoring windows default keyboard.
- [90465] Help viewer need to select File | Reload menu item, after you change the encoding option (the sub-menus under Options | Encoding.)
- [90162] (Japanese Linux only) Closing dialog with XIM window open causes JBuilder to hang.
- [90839] (Windows 2000 Chinese edition) If you can not display Chinese characters, you need to create a font.properties.zh.NT5.0 under <jdk1.3>/jre/lib directory. Please check the JavaSoft's web site to fix this file (in English.) "Adding Fonts to the Java Runtime".
- [91509] The Linux and Solaris versions of the jdk.config files should include the following line:
  `#vmparam -Dfile.encoding=ISO8859_1`
  Uncomment this line if you are having problems with your default file encoding. This problem is evident in some locales.

[ top ]

## Documentation

Check the JBuilder Technical Publication web site, http://www.borland.com/techpubs/jbuilder, for updates to the documentation.

All of the printed documentation is also available in PDF format on your JBuilder 4 product CD. Look in the `pdf` directory for the following files:

> PDF File | Printed Manual
> --- | ---
> `database.pdf` | Database Application Developer's Guide
> `enterprise.pdf` | Enterprise Application Developer's Guide Team Development using JBuilder Web Application Developer's Guide Distributed Application Developer's Guide Enterprise JavaBeans Developer's Guide
> `java-jb.pdf` | Learning Java with JBuilder Quick Start Getting Started with Java Tutorials
> `jdspg.pdf` | JDataStore Developer's Guide
> `pg.pdf` | Building Applications with JBuilder

If you downloaded your version of JBuilder 4, the PDF files are also available for download from the JBuilder Technical Publication web site, http://www.borland.com/techpubs/jbuilder.

### Known Problems:

- References in the documentation to the `.jbuilder` directory should refer to the `.jbuilder4` directory.
- [83463] In the "Agg Property Editor" help topic, the description of the "Aggregate Column" is incorrect. The aggregate column is the column whose values are being summarized (for some subset of rows or for the whole dataset). The column that this summary is stored in does not have a name.
- In "Developing international applications" in the Quick Start, `IntlDemo.jpr` should be `IntlDemo.jpx`
- In "Tutorial: Creating JavaServer Pages (JSP) using the JSP Wizard" in the Web Application Developer's Guide, the following corrections are required:
  - [91566] The paragraph before the "Adding functionality to the JSP" section says "The Tomcat library has been added to this project". After creating a JSP, no libraries get added to your project.
  - [91569] The tutorial recommends that the name entered in the JSP wizard be "JSPwithCountingBean". This will create a java file named JSPwithCountingBeanBean.java, and will generate a "JSPwithCountingBeanBeanId" reference in the .jsp file. The rest of the tutorial asks to copy a line that refers to JSPwithCountingBeanId: the second "Bean" missing from the name. This will cause the JSP that the user modifies according to tutorial instructions not to work (compiler error).
- [91845] Cannot print topics from the Help Viewer that contain large blocks of source code. The topics will print until they reach the code block, then begins printing out multiple blank pages.
  Workaround: Print the topics using your web browser or from the PDF files available on your product CD or from the JBuilder web site.

[ top ]

Apache Software Foundation conditions and disclaimer:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.
4. The names "Apache" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.
5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE (Tomcat) IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

[ top ]